Language/OS - Multiplatform Resource Library/LANGUAGE OS.iso/cpp_libs/cool/ge_cool.lha/GE_COOL2.1/man/oldman3/Bit_Set.3T

Text File | 1992-06-26 | 13KB | 439 lines

.TH BIT_SET
.SH NAME
Bit_Set  Efficient, dynamic bit sets
.SH SYNOPSIS
#include <cool/Bit_Set.h>
.SH DESCRIPTION
The
 Bit_Set
class is publicly derived from the

class and implements
efficient bit sets. These bits are stored in an arbitrary-length vector of
bytes (unsigned
 char )
large enough to represent the specified number of
elements. A bit set is indexed by integer values: Zero represents the first
bit, one the second, two the third, and so on with each integer value actually
indicating the zero-relative bit position in the bit vector. Elements can be
integers, enum values, constant symbols from the enumeration package, or any
other type of object or expression that results in an integral value. All
operations involving bit shifting are performed in byte increments, giving the
most efficient operation on common hardware architectures.
.SH Base Classes
None
.SH Friend Classes
None
.SH Public Constructors
.TP
 Bit_Set ();
Allocates a bit set of the default size (1 byte).
.TP
\f3Bit_Set (unsigned int \f2number\f3);\f1
Allocates a bit set with at least enough storage for
 number
elements.
.TP
\f3Bit_Set (const Bit_Set& \f2bs\f3);\f1
Duplicates the size and elements of another bit set object
 bs .
.SH Member Functions
.TP
 inline int capacity () const;
Returns the maximum number of elements that the bit set can hold.
.TP
 void clear ();
Removes all elements from the bit set and adjusts the appropriate counts.
.TP
 inline Bit_Set_state& current_position () const;
Returns the state information associated with the current position. This
function should be used with the \f3Iterator<Type>\f1 class to save and restore the
current position, thus facilitating multiple iterators over an instance of bit
set.
.TP
\f3Boolean find (unsigned int \f2n\f3);\f1
Searches the bit set for the \f2nt\f1h zero-relative bit. If the bit is set, this
function updates the current position and returns

 TRUE ;
otherwise, this
function invalidates the current position and returns

 FALSE .
If
 n
is out of
range, an
 \f3\f3Error\f1\f1
exception is raised.
.TP
 inline Boolean is_empty () const;
Returns

 TRUE
if the bit set contains no elements; otherwise, this function
returns

 FALSE .
.TP
 int length () const;
Returns the number of elements in the bit set.
.TP
 Boolean next ();
Advances the current position pointer to the next element in the bit set and
returns

 TRUE .
If the current position is invalid, this function advances to the
first element and returns

 TRUE .
If advancing past the last element in the bit
set, this function invalidates the current position and returns

 FALSE .

.TP
\f3Boolean next_difference (const Bit_Set& \f2bs\f3);\f1
Determines the next element in the difference of the set object and
 bs .
This
function sets the current position in the set object to that element and
returns

 TRUE .
If no more elements are in the different, this function
invalidates the current position and returns

 FALSE .
.TP
\f3Boolean next_intersection (const Bit_Set& \f2bs\f3);\f1
Determines the next element in the intersection of the set object and
 bs .
This
function sets the current position of the set object to that element and
returns

 TRUE .
If no more elements are in the intersection, this function
invalidates the current position and returns

 FALSE .
.TP
\f3Boolean next_union (const Bit_Set& \f2bs\f3);\f1
Determines the next element in the union of the set object and
 bs .
This
function sets the current position of the set object to that element and
returns

 TRUE .
If no more elements are in the union, this function invalidates
the current position and returns

 FALSE .
.TP
\f3Boolean next_xor (const Bit_Set& \f2bs\f3);\f1
Determines the next element in the exclusive-or of the set object and
 bs .
This
function sets the current position of the set object to that element and
returns

 TRUE .
If no more elements are in the exclusive-or, this function
invalidates the current position and returns

 FALSE .
.TP
 Bit_Set operator\- ();
Overloads the unary minus operator to return the complement bit set.
.TP
\f3Bit_Set operator- (const Bit_Set& \f2bs\f3);\f1
Determines the logical difference of the set object and
 bs
and returns the
result. This function invalidates the current position of the set object.
.TP
 inline Bit_Set operator~ ();
Returns the complement of a bit set.
.TP
\f3Bit_Set operator^ (const Bit_Set& \f2bs\f3);\f1
Determines the logical exclusive-or of the set object and
 bs
and returns the
result. This function invalidates the current position of the set object.
.TP
\f3Bit_Set operator& (const Bit_Set& \f2bs\f3);\f1
Determines the logical intersection of the set object and
 bs
and returns the
result. This function invalidates the current position of the set object.
.TP
\f3Bit_Set operator| (const Bit_Set& \f2bs\f3);\f1
Determines the logical union of the set object and
 bs
and returns the result.
This function invalidates the current position of the set object.
.TP
\f3Bit_Set& operator= (const Bit_Set& \f2bs\f3);\f1
Duplicates the size and elements of another bit set. This function invalidates
the current position of the set object and returns a reference to the updated
object.
.TP
\f3Bit_Set& operator\-= (const Bit_Set& \f2bs\f3);\f1
Determines the logical difference of the set object and
 bs
and modifies the
source with the result. This function returns a reference to the modified bit
set and invalidates the current position of the set object.
.TP
\f3Bit_Set& operator^= (const Bit_Set& \f2bs\f3);\f1
Determines the logical exclusive-or of the set object and
 bs
and modifies the
source with the result. This function returns a reference to the modified bit
set and invalidates the current position of the set object.

.TP
\f3Bit_Set& operator&= (const Bit_Set& \f2bs\f3);\f1
Determines the logical intersection of the set object and
 bs
and modifies the
source with the result. This function returns a reference to the modified bit
set and invalidates the current position of the set object.
.TP
\f3Bit_Set& operator|\^= (const Bit_Set& \f2bs\f3);\f1
Determines the logical union of the set object and
 bs
and modifies the source
with the result. This function returns a reference to the modified bit set and
invalidates the current position of the set object.
.TP
\f3Boolean operator== (const Bit_Set& \f2bs\f3) const;\f1
Overloads the equality operator for the
 Bit_Set
class. This function returns

 TRUE
if the sets have an equal number of elements with the same values;
otherwise, this function returns

 FALSE .
.TP
\f3inline Boolean operator!= (const Bit_Set& \f2bs\f3) const;\f1
Overloads the inequality operator for the
 Bit_Set
class. This function returns

 TRUE
if the sets have an unequal number of elements or unequal values
otherwise, this function returns

 FALSE .
.TP
\f3inline Boolean operator[\^] (int \f2n\f3) const;\f1
Returns

 TRUE
or

 FALSE
to indicate the setting of the zero-relative \f2n\f1th bit. If
the index is out of range, an
 \f3\f3Error\f1\f1
exception is raised.
.TP
 Boolean prev ();
Moves the current position pointer to the previous element in the bit set and
returns

 TRUE .
If the current position is invalid, this function moves to the
last element and returns

 TRUE .
If moving to the previous element passes the
first element in the bit set, this function invalidates the current position
and returns

 FALSE .
.TP
\f3Boolean put (int \f2n\f3);\f1
Adds the zero-relative \f2n\f1th element to the bit set. If the bit vector is not
large enough and it can grow, this function allocates enough storage, copies
the old bit set elements, updates the current position, and returns

 TRUE ;
otherwise, this function returns

 FALSE .
If the index is out of range, an
 \f3\f3Error\f1\f1
exception is raised.
.TP
\f3Boolean put (int \f2start\f3, int \f2end\f3);\f1
Adds the specified range of elements (inclusive) to the bit set by setting the
appropriate zero-relative bits. If the bit vector is not large enough and it
can grow, this function allocates enough storage, copies the old bit set
elements, updates the current position, and returns

 TRUE ;
otherwise, this
function returns

 FALSE .
If the \f2start\f1 or \f2end\f1 are out of range, an
 \f3\f3Error\f1\f1
exception is raised.
.TP
 Boolean remove ();
This function removes the element at the current position, sets the current
position to the element immediately following the element removed (if not at
the end of the vector), and returns

 TRUE .
If the element is at the end of the
bit vector, this function removes the element, invalidates the current
position, and returns

 TRUE .
Otherwise, this function invalidates the current
position and returns

 FALSE .
If the current position is invalid, an
 \f3\f3Error\f1\f1
exception is raised and this function returns

 FALSE .
.TP
\f3Boolean remove (int \f2n\f3);\f1
Searches for the zero-relative \f2n\f1th element. If the element is found, this
function removes the element, sets the current position to the element
immediately following the element removed, and returns

 TRUE .
If the element is
found but at the end of the bit vector, this function removes the element,
invalidates the current position, and returns

 TRUE .
Otherwise, this function
returns

 FALSE .
If the index is out of range, an
 \f3\f3Error\f1\f1
exception is raised.
.TP
\f3Boolean remove (int \f2start\f3, int \f2end\f3);\f1
Searches for the specified range of elements. If the range is found, this
function removes the range of elements, sets the current position to the
starting element position, and returns

 TRUE .
Otherwise, this function returns

 FALSE .
If either index is out of range, an
 \f3\f3Error\f1\f1
exception is raised.
.TP
 inline void reset ();
Invalidates the current position.
.TP
\f3resize (int \f2number);\f1
Resizes the bit set for at least
 number
elements. This function invalidates the
current position.
.TP
\f3Boolean search (const Bit_Set& \f2bs\f3) const;\f1
Determines if
 bs
is a subset of the bit set object. If found, this function
returns

 TRUE ;
otherwise, this function returns

 FALSE .
.TP
\f3inline void set_alloc_size (int \f2number\f3);\f1
Sets the allocation growth size to
 number
of bytes. The growth allocation size
is used when the growth ratio is zero. Default allocation growth size is four
bytes.
.TP
\f3inline void set_difference (const Bit_Set& \f2bs\f3);\f1
Determines the logical difference of
 bs
and the bit set object, modifing the
source with the result. This function invalidates the current position in the
bit set object.
.TP
\f3inline void set_growth_ratio (float \f2ratio\f3);\f1
Updates the growth ratio for this instance of a bit set to
  ratio.
When a bit
set needs to grow, the current size is multiplied by the ratio to determine the
new size. If
 ratio
is negative, and
 \f3\f3Error\f1\f1
exception is raised.
.TP
\f3inline void set_intersection (const Bit_Set& \f2bs\f3);\f1
Determines the logical intersection of
 bs
and the bit set object, modifing the
source with the result. This function invalidates the current position of the
bit set object.
.TP
\f3inline void set_union (const Bit_Set& \f2bs\f3);\f1
Determines the logical union of
 bs
and the bit set object, modifing the source
with the result. This function invalidates the current position of the bit set
object.
.TP
\f3inline void set_xor (const Bit_Set& \f2bs\f3);\f1
Determines the logical exclusive-or of
 bs
and the bit set object, modifing the
source with the result. This function invalidates the current position of the
bit set object.
.TP
 inline int value ();
Returns the value (zero-relative bit position) of the bit at the current
position. If the current position is invalid, an
 \f3\f3Error\f1\f1
exception is raised.
.SH Friend Functions
.TP
\f3friend ostream& operator<< (ostream& \f2os\f3, const \f2Bit_Set& bs\f3);\f1
Overloads the output operator for a reference to a
 Bit_Set
object to provide a
formatted output capability for the class.
.TP
\f3inline friend ostream& operator<< (ostream& \f2os\f3, const \f2Bit_Set* bs\f3);\f1
Overloads the output operator for a reference to a
 Bit_Set
object to provide a
formatted output capability for the class.
.SH COPYRIGHT

Copyright (C) 1991 Texas Instruments Incorporated.

Permission is granted to any individual or institution to use, copy, modify,
and distribute this software, provided that this complete copyright and
permission notice is maintained, intact, in all copies and supporting
documentation.

Texas Instruments Incorporated provides this software "as is" without
express or implied warranty.